package com.twitter.product_mixer.core.pipeline.candidate

import com.twitter.product_mixer.core.model.common.identifier.CandidatePipelineIdentifier
import com.twitter.product_mixer.core.model.common.presentation.CandidateWithDetails
import com.twitter.product_mixer.core.pipeline.Pipeline
import com.twitter.product_mixer.core.pipeline.PipelineQuery
import com.twitter.stitch.Arrow

/**
 * A Candidate Pipeline
 *
 * This is an abstract class, as we only construct these via the [[CandidatePipelineBuilder]].
 *
 * A [[CandidatePipeline]] is capable of processing requests (queries) and returning candidates
 * in the form of a [[CandidatePipelineResult]]
 *
 * @tparam Query the domain model for the query or request
 */
//这段代码定义了一个名为CandidatePipeline的抽象类，它是Twitter的产品混合器（Product Mixer）核心管道的一部分。
// CandidatePipeline类扩展了一个泛型管道接口，并专门用于处理查询并返回候选数据的结果。下面是对这段代码的详细解释：
//abstract class: CandidatePipeline被定义为一个抽象类，这意味着它不能直接实例化，而是需要被其他类扩展或实现。
//-Query <: PipelineQuery: 这是一个类型参数，表示CandidatePipeline可以处理的查询类型。-Query是逆变的，意味着如果A是B的子类型，则CandidatePipeline[B]是CandidatePipeline[A]的子类型。
//private[candidate]: 这表明该类在candidate包内是私有的，限制了它的可见性和访问范围。
//extends Pipeline[CandidatePipeline.Inputs[Query], Seq[CandidateWithDetails]]: CandidatePipeline扩展了一个管道接口，其输入是CandidatePipeline.Inputs[Query]，输出是CandidateWithDetails的序列。
abstract class CandidatePipeline[-Query <: PipelineQuery] private[candidate]
    extends Pipeline[CandidatePipeline.Inputs[Query], Seq[CandidateWithDetails]] {
  //config: 表示管道的配置，这是一个抽象成员，需要由扩展类提供具体实现。
  //arrow: 是一个处理逻辑的箭头（Arrow），它定义了如何将输入转换为CandidatePipelineResult。
  //identifier: 是管道的唯一标识符。
  override private[core] val config: BaseCandidatePipelineConfig[Query, _, _, _]
  override val arrow: Arrow[CandidatePipeline.Inputs[Query], CandidatePipelineResult]
  override val identifier: CandidatePipelineIdentifier
}

//object CandidatePipeline: 这是CandidatePipeline类的伴生对象，提供了类级别的功能。
//case class Inputs[+Query <: PipelineQuery]: 这是一个用于封装输入数据的案例类。它包含两个字段：query（查询对象）和existingCandidates（已存在的候选数据序列）。
//+Query <: PipelineQuery: 这里的+Query是协变的，意味着如果A是B的子类型，则Inputs[A]是Inputs[B]的子类型。
object CandidatePipeline {
  case class Inputs[+Query <: PipelineQuery](
    query: Query,
    existingCandidates: Seq[CandidateWithDetails])
}
